<!--
-File         $Id: Setup.html 1142 2011-06-12 15:18:01Z mrook $
-License      GNU FDL (http://www.gnu.org/copyleft/fdl.html)
-Copyright    2002, turing
-Author       alex black, enigma@turingstudio.com
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/2000/REC-xhtml1-20000126/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Phing Guide - Setup</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<link rel="Stylesheet" rev="Stylesheet" href="../css/Documentation.css"
	type="text/css" media="All" charset="iso-8859-1" />
</head>
<body>

	<h1>
		<a name="SettingUpPhing"></a>Setting-Up Phing
	</h1>

	<p>The goal of this chapter is to help you obtain and correctly
		setup and execute Phing on your operating system. Once you setup Phing
		properly you shouldn't need to revisit this chapter, unless you're
		re-installing or moving your installation to another platform.</p>

	<h2>
		<a name="SystemRequirements"></a>System Requirements
	</h2>

	<p>To use Phing you must have installed PHP version 5.2 or above
		compiled --with-libxml2, as well as --with-xsl if you want to make use
		of advanced functionality.</p>

	<p>
		For more information on PHP and the required modules see the PHP <a
			href="Bibliography.html#php">[php]</a> website. For a brief list of
		software dependencies see below.
	</p>

	<h3>
		<a name="OperatingSystems"></a>Operating Systems
	</h3>

	<p>Designed for portability from the get go, Phing runs on all
		platforms that run PHP. However some advanced functionality may not
		work properly or is simply ignored on some platforms (i.e. chmod on
		the Windows platform).</p>

	<p>To get the most out of Phing, a Unix style platform is
		recommended. Namely: Linux, FreeBSD, OpenBSD, etc.</p>

	<h3>
		<a name="SoftwareDependencies"></a>Software Dependencies
	</h3>

	<p>For a detailed list of required / optional sofware and libraries, refer to
		the following table of Software Dependencies.</p>

	<p>NB: This list is not exhaustive, please refer to individual
		Phing tasks to find out additional software requirements.</p>

	<table>
		<caption>Software Dependencies</caption>
		<thead>
			<tr>
				<th>Software</th>
				<th>Required for</th>
				<th>Source</th>
			</tr>
		</thead>
		<tbody>
			<tr>
				<td>PHP 5.2+</td>
				<td>Execution</td>
				<td><a href="http://www.php.net">http://www.php.net</a>
				</td>
			</tr>
			<tr>
				<td>PHPUnit 3.4.0+</td>
                <td>Optional; enables additional task(s)</td>
				<td><a href="http://www.phpunit.de">http://www.phpunit.de</a>
				</td>
			</tr>
			<tr>
				<td>Xdebug 2.0.0+</td>
                <td>Optional; enables additional task(s)</td>
				<td><a href="http://www.xdebug.org">http://www.xdebug.org</a>
				</td>
			</tr>
            <tr>
                <td>SimpleTest 1.0.1 beta+</td>
                <td>Optional; enables additional task(s)</td>
                <td><a href="http://simpletest.sourceforge.net">http://simpletest.sourceforge.net</a>
                </td>
            </tr>
            <tr>
                <td>Creole 1.1.0+</td>
                <td>Optional; enables additional task(s)</td>
                <td><a href="http://creole.phpdb.org">http://creole.phpdb.org</a>
                </td>
            </tr>
            <tr>
                <td>PhpDocumentor 1.4.0+ (PEAR package)</td>
                <td>Optional; enables additional task(s)</td>
                <td><a href="http://pear.php.net/package/PhpDocumentor" target="_blank">http://pear.php.net/package/PhpDocumentor</a>
                </td>
            </tr>
			<tr>
				<td>VersionControl_SVN (PEAR package)</td>
                <td>Optional; enables additional task(s)</td>
				<td><a href="http://pear.php.net/package/VersionControl_SVN" target="_blank">http://pear.php.net/package/VersionControl_SVN</a>
				</td>
			</tr>
            <tr>
                <td>VersionControl_Git (PEAR package)</td>
                <td>Optional; enables additional task(s)</td>
                <td><a href="http://pear.php.net/package/VersionControl_Git" target="_blank">http://pear.php.net/package/VersionControl_Git</a>
                </td>
            </tr>            
            <tr>
                <td>PHP_CodeSniffer (PEAR package)</td>
                <td>Optional; enables additional task(s)</td>
                <td><a href="http://pear.php.net/package/PHP_CodeSniffer" target="_blank">http://pear.php.net/package/PHP_CodeSniffer</a>
                </td>
            </tr>
            <tr>
                <td>Archive_Tar (PEAR package)</td>
                <td>Optional; enables additional task(s)</td>
                <td><a href="http://pear.php.net/package/Archive_Tar" target="_blank">http://pear.php.net/package/Archive_Tar</a>
                </td>
            </tr>
            <tr>
                <td>Services_Amazon_S3 (PEAR package)</td>
                <td>Optional; enables additional task(s)</td>
                <td><a href="http://pear.php.net/package/Services_Amazon_S3" target="_blank">http://pear.php.net/package/Services_Amazon_S3</a>
                </td>
            </tr>
            <tr>
                <td>HTTP_Request2 (PEAR package)</td>
                <td>Optional; enables additional task(s)</td>
                <td><a href="http://pear.php.net/package/HTTP_Request2" target="_blank">http://pear.php.net/package/HTTP_Request2</a>
                </td>
            </tr>
            <tr>
                <td>PHP Depend</td>
                <td>Optional; enables additional task(s)</td>
                <td><a href="http://www.pdepend.org" target="_blank">http://www.pdepend.org</a>
                </td>
            </tr>
            <tr>
                <td>PHP Mess Detector</td>
                <td>Optional; enables additional task(s)</td>
                <td><a href="http://www.phpmd.org" target="_blank">http://www.phpmd.org</a>
                </td>
            </tr>
            <tr>
                <td>PHP Copy/Paste Detector</td>
                <td>Optional; enables additional task(s)</td>
                <td><a href="http://pear.phpunit.de" target="_blank">http://pear.phpunit.de</a>
                </td>
            </tr>
            <tr>
                <td>DocBlox 0.11.0+</td>
                <td>Optional; enables additional task(s)</td>
                <td><a href="http://www.docblox-project.org" target="_blank">http://www.docblox-project.org</a>
                </td>
            </tr>
		</tbody>
	</table>

	<p>
		<strong>Phing does not work with safe mode enabled! </strong>
	</p>
	<h2>
		<a name="ObtainingPhing"></a>Obtaining Phing
	</h2>

	<p>Phing is free software distributed under the terms of the LGPL.</p>

	<h3>
		<a name="DistributionFiles"></a>Distribution Files
	</h3>

	<p>There are several ways to get a Phing distribution package. If
		you do not want to participate in developing Phing itself it is
		recommended that you get the latest snapshot or stable packaged
		distribution. If you are interested in helping with Phing development,
		get a CVS revision of the files, as described below.</p>

	<p>
		The easiest way to obtain the distribution package is to visit the
		Phing website <a href="Bibliography.html#phing">[phing] </a>and
		download the current distribution package in the format you desire.
	</p>
	<p>As of version 2.0, you have the option of downloading a
		PEAR-installable package or the full phing distribution. If you wish
		to modify phing we suggestion downloading the full version so that you
		can (e.g.) create your own PEAR package. If you simply wish to use
		Phing for your own project or need it to build another package,
		download &amp; install the PEAR package.</p>

	<h3>
		<a name="GettingFromCVS"></a>Getting A Development Copy From
		Subversion
	</h3>

	<p>You are encouraged to contibute to the development of Phing. If
		you want to participate or if you are simply interested in the latest
		features and development, obtain a Subversion copy as described in the
		following paragraphs.</p>

	<p>
		<strong>The SVN revisions of Phing are not bullet-proof and
			may fail to execute properly on your machine. Only obtain the
			development versions if you are absolutely aware of limitations and
			constraints of such an action. Additionally you should sign up to the
			development mailinglist to report and notice errors and
			incompatibilities.</strong>
	</p>

	<p>
		We assume that you are running a Unix style operating system. So we
		expect the Subversion software is installed ant the
		<tt>svn</tt>
		executable is in your system's search path. However, the steps for a
		Windows based system are very similar. There is plenty additional
		information available on how to use Subversion <a
			href="Bibliography.html#cvs-howto">[svn-howto]</a>.
	</p>

	<p>To check out the project source repository type:</p>

	<pre>$&gt; svn checkout http://svn.phing.info/trunk</pre>

	<p>
		You can also browse the entire Phing source (including previous
		versions and development branches) on <a
			href="http://www.phing.info/trac/browser" target="_blank">http://www.phing.info/trac/browser</a>.
	</p>

	<h2>
		<a name="Setup.PearInstall"></a>PEAR Install
	</h2>
	<p>The easiest way to install Phing is using the PEAR installer.
		Provided that the package you downloaded is a the PEAR-ready package,
		you can install Phing simply from the command line (Unix or Windows):</p>
	<pre>$&gt; pear channel-discover pear.phing.info
$&gt; pear install phing/phing</pre>
	<p>The pear installer will check any dependencies and place the
		phing script (phing or phing.bat) into your PHP script directoy (i.e.
		where the &quot;pear&quot; script resides).</p>

	<h2>
		<a name="Setup.NonPearInstall"></a>Non-PEAR Install
	</h2>

	<p>
		If you are not using the PEAR installer, you will need to setup your
		environment in order to run Phing. The distribution of Phing consists
		of three directories: <em>bin</em> , <em>docs</em> and <em>classes</em>.
		Only the <em>bin</em>, <em>classes</em> and <em>etc</em> directories
		are required to run Phing. To install Phing, choose a directory and
		uncompress the distribution file in that directory (you may already
		have done this in a prior step). This directory will be known as <em>PHING_HOME</em>
		.
	</p>

	<p>
		<strong>On earlier Windows installations, the script used to
			launch Phing will have problems if PHING_HOME is a long filepath.
			This is due to limitations in the OS's handling of the "for"
			batch-file statement. It is recommended, therefore, that Phing be
			installed in a short path, such as C:\opt\phing.</strong>
	</p>

	<p>Before you can run Phing there is some additional set up you
		will need to do perform:</p>

	<ul>
		<li>Add the full path to the <em>bin/</em> directory to your
			path.</li>
		<li>Set the <em>PHING_HOME</em> environment variable to the
			directory where you installed Phing. On some operating systems the
			Phing wrapper scripts can guess PHING_HOME (Unix dialects and
			Windows). However, it is better to not rely on this behavior.</li>
		<li>Set the <em>PHP_COMMAND</em> environment variable to where
			your Php binary is located (including the binary i.e.
			PHP_COMMAND=/usr/bin/php).</li>
		<li>Set the <em>PHP_CLASSPATH</em> environment variable (see the
			section below). This should be set at least point to
			PHING_HOME/classes. Alternatively, you can also just add the
			phing/classes directory to your PHP include_path ini setting.</li>
		<li>Check your php.ini file to make sure that you have the
			following settings:
			<ul>
				<li>max_execution_time = 0 <em>// unlimited execution time</em>
				</li>
				<li>memory_limit = 32M <em>// you may need more memory
						depending on size of your build files</em>
				</li>
			</ul></li>
	</ul>

	<p>If you are using Phing in conjunction with another application,
		you may need to add additional paths to PHP_CLASSPATH.</p>

	<h3>
		<a name="Unix"></a>Unix
	</h3>

	<p>
		Assuming you are running a Unix dialect operating system with the <em>bash
			bourne shell</em> and Phing is installed in
		<tt>/opt/phing</tt>
		. The following sets up the environment properly:
	</p>

	<pre>
  export PHP_COMMAND=/usr/bin/php
  export PHING_HOME=/opt/phing
  export PHP_CLASSPATH=${PHING_HOME}/classes
  export PATH=${PATH}:${PHING_HOME}/bin
</pre>
	<h3>
		<a name="Windows"></a>Windows
	</h3>

	<p>On the Windows platfrom, assuming Phing is installed in
		c:\opt\phing. The following sets up your environment:</p>

	<pre>
  set PHP_COMMAND=c:\opt\php\php.exe
  set PHING_HOME=c:\opt\phing
  set PHP_CLASSPATH=c:\opt\phing\classes
  set PATH=%PATH%;%PHING_HOME%\bin
</pre>
	<h3>Advanced</h3>

	<p>There are lots of variants that can be used to run/prepare
		Phing. You need at least the following:</p>
	<ul>
		<li>If you want Phing to be able to use other packages / classes,
			you can either add them to the PHP_CLASSPATH or to PHP's
			include_path.</li>
		<li>Some Tasks in phing/tasks/ext may require 3rd party libraries
			to be installed. Generally, tools with compatible license (and stable
			releases) are included in phing/lib so that outside dependencies can
			be avoided. PEAR libs will not, however, be bundled with Phing since
			they are generally bundled with PHP. If you are using a 3rd party
			task, see the Task documentation to be aware of any dependencies.</li>
	</ul>

	<p>
		You are now ready to use the
		<tt>phing</tt>
		command at your command prompt, from everywhere in your directory
		tree.
	</p>

	<h2>
		<a name="CallingPhing"></a>Calling Phing
	</h2>

	<p>Now you are prepared to execute Phing on the command line or via
		script files. The following section briefly describe how to properly
		execute phing.</p>

	<h3>
		<a name="CommandLine"></a>Command Line
	</h3>

	<p>Phing execution on the command line is simple. Just change to
		the directory where your buildfile resides and type</p>

	<pre>
$ phing [targetname]
</pre>

	<p>
		at the command line (where [targetname] is the target you want to be
		executed). Optionally, you may specify command line arguments as
		listed in <a
			href="appendixes/AppendixA-FactSheet.html#CommandLineArguments">Appendix
			A</a>.
	</p>

	<p>
		For example, the following command line calls the default buildscript
		<i>build.xml</i> using the default target with the propery <i>ftp.upload</i>
		set to true.
	</p>
	<pre>
$ phing -Dftp.upload=true
</pre>

</body>
</html>

